
<html>
  
  <HEAD>
    
    <link rel="stylesheet" href="style/default.css" type="text/css">
    
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  
    <title>JAXB RI 2.1.9 fcs -- Vendor Customizations
    </title>
    <link rel="alternate" href="https://jaxb.dev.java.net/servlets/ProjectNewsRSS" type="application/rss+xml">
  </HEAD>
  
  <BODY>
    <h1>
      <banner>
    Java
        <sup>
          <font size="-2">TM</font>
        </sup> Architecture for XML Binding
  
      </banner>
      <br>
      Vendor Customizations 
    
    </h1>
    <center>
      <b>Implementation Version:</b> 2.1.9 fcs
      <br>
    </center>
    <table class="navbar" cellspacing="0">
      <tr>
        <td class="inactive">
          <a href="index.html">JAXB 2.0</a>
        </td>
        <td class="inactive">
          <a href="xjc.html">Tools</a>
        </td>
        <td class="inactive">
          <a href="jaxb-1_0.html">JAXB 1.0.x</a>
        </td>
        <td class="active">
          <a>JAXB RI Extensions</a>
        </td>
        <td class="inactive">
          <a href="community.html">JAXB Community</a>
        </td>
      </tr>
    </table>
    <div class="subnavbar">
      <ul>
        <li class="first">
          <a href="vendor.html">
            <span>Overview </span>
          </a>
        </li>
        <li>
          <a href="vendorProperties.html">
            <span>Runtime Properties </span>
          </a>
        </li>
        <li>
          <a href="vendorCustomizations.html">
            <span class="active">XJC Customizations </span>
          </a>
        </li>
        <li>
          <a href="vendorSchemaLangs.html">
            <span>DTD </span>
          </a>
        </li>
        <li>
          <a href="developPlugins.html">
            <span>Develop Plugins </span>
          </a>
        </li>
      </ul>
    </div>
    
    <header></header>

	
    <h2>Customizations</h2>
	
	
    <p>
	The JAXB RI provides additional customizations that are not defined
	by the JAXB specification.  Note the following: 
	
	
    <ul>
		
      <li>These features may only be used when the JAXB XJC binding compiler 
		    is run in the 
        <tt>"-extension"</tt> mode.
      </li>
		
      <li>All of the JAXB RI vendor extensions are defined in the 
		    
        <tt>"http://java.sun.com/xml/ns/jaxb/xjc"</tt> namespace.
      </li>
		
      <li>The namespaces containing extension binding declarations are specified 
			to a JAXB processor by the occurrence of the global attribute 
			
        <tt>@jaxb:extensionBindingPrefixes</tt> within an instance of 
			
        <tt>&lt;xs:schema&gt;</tt> element. The value of this attribute is a 
			whitespace-separated list of namespace prefixes.  For more information, 
			please refer to section 6.1.1 of the JAXB Specification.
      </li>
	
    </ul>
		
	
    <h3>Index of Customizations</h3>
	
    <ul>
		
      <li>
        <a href="#scd">Identifying customization targets by Schema Component Designator</a>
      </li>
		
      <li>
        <a href="#superclass">&lt;xjc:superClass&gt;</a> - Extending a Common Super Class
      </li>
		
      <li>
        <a href="#superinterface">&lt;xjc:superInterface&gt;</a> - Extending a Common Super Interface
      </li>
		
      <li>
        <a href="#javaType">&lt;xjc:javaType&gt;</a> - Enhanced &lt;jaxb:javaType&gt; customization
      </li>
		
      <li>
        <a href="#simple">&lt;xjc:simple&gt;</a> - Experimental simpler&amp;better binding mode
      </li>
		
      <li>
        <a href="#treatRestrictionLikeNewType">&lt;xjc:treatRestrictionLikeNewType&gt;</a> - Alternative derivation-by-restriction binding mode
      </li>
		
      <li>
        <a href="#substitutable">&lt;xjc:substitutable&gt;</a> - Allow separate compilations to perform element substitutions
      </li>
		
	
    </ul>
	
	
	
    <a name="scd"></a>
	
    <h3>SCD Support</h3>
	
    <p>The JAXB RI supports the use of 
      <a href="http://www.w3.org/TR/2005/WD-xmlschema-ref-20050329/">schema component designator</a> as a means of specifying the customization target (of all standard JAXB customizations as well as vendor extensions explained below.) To use this feature, use the 
      <tt>scd</tt> attribute on &lt;bindings&gt; element instead of the 
      <tt>schemaLocation</tt> and 
      <tt>node</tt> attributes.
	

      <pre class="code">
&lt;bindings xmlns:tns="http://example.com/myns" xmlns="http://java.sun.com/xml/ns/jaxb" version="2.1"&gt;
  &lt;bindings <font color="red">scd="tns:foo"</font>&gt;
    &lt;!--this customization applies to the global element declaration 'foo'
              in the http://example.com/myns namespace --&gt;
    &lt;class name="FooElement"/&gt;
  &lt;/bindings&gt;
  &lt;bindings <font color="red">scd="~tns:bar"</font>&gt;
    &lt;!--this customization applies to the global type declaration 'bar'
              in the http://example.com/myns namespace --&gt;
    &lt;class name="BarType"/&gt;
  &lt;/bindings&gt;
&lt;/bindings&gt;
</pre>
	
    
    <p>
		Compared to the standard XPath based approach, SCD allows more robust and concise way of identifying a target of a customization. For more about SCD, refer to the scd example. Note that SCD is a W3C working draft, and may change in the future.
	
	
      <a name="superclass"></a>
	
    
    <h3>Extending a Common Super Class</h3>
	
    <p>The 
      <tt>&lt;xjc:superClass&gt;</tt> customization allows you to specify the
	fully qualified name of the Java class that is to be used as the super class of all the generated implementation classes.
	The  
	
      <tt>&lt;xjc:superClass&gt;</tt> customization can only occur within your
	
      <tt>&lt;jaxb:globalBindings&gt;</tt> customization on the 
      <tt>&lt;xs:schema&gt;</tt> 
	element:
    


    <pre class="code">
&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
           <font color="red">xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
           jaxb:extensionBindingPrefixes="xjc"</font>
           jaxb:version="2.0"&gt;

    &lt;xs:annotation&gt;
       &lt;xs:appinfo&gt;
          &lt;jaxb:globalBindings&gt;
              <font color="red">&lt;xjc:superClass name="org.acme.RocketBooster"/&gt;</font>
          &lt;/jaxb:globalBindings&gt;
       &lt;/xs:appinfo&gt;
    &lt;/xs:annotation&gt;
.
.
.
&lt;/xs:schema&gt;
</pre>

	
    <p>In the sample above, the 
      <tt>&lt;xjc:superClass&gt;</tt> customization will
	cause all of the generated implementation classes to extend the named class,
	
      <tt>org.acme.RocketBooster</tt>.
    
  
  
  
	
	
	
    <a name="superinterface"></a>
	
    <h3>Extending a Common Super Interface</h3>
	
    <p>The 
      <tt>&lt;xjc:superInterface&gt;</tt> customization allows you to specify the
	fully qualified name of the Java interface that is to be used as the root interface of all the generated interfaces.
	
	The  
	
      <tt>&lt;xjc:superInterface&gt;</tt> customization can only occur within your
	
      <tt>&lt;jaxb:globalBindings&gt;</tt> customization on the 
      <tt>&lt;xs:schema&gt;</tt> 
	element:
    


    <pre class="code">
&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
           <font color="red">xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
           jaxb:extensionBindingPrefixes="xjc"</font>
           jaxb:version="2.0"&gt;

    &lt;xs:annotation&gt;
       &lt;xs:appinfo&gt;
          &lt;jaxb:globalBindings&gt;
           <font color="red">&lt;xjc:superInterface name="org.acme.RocketBooster"/&gt;</font>
          &lt;/jaxb:globalBindings&gt;
       &lt;/xs:appinfo&gt;
    &lt;/xs:annotation&gt;
.
.
.
&lt;/xs:schema&gt;
</pre>

	
    <p>In the sample above, the 
      <tt>&lt;xjc:superInterface&gt;</tt> customization will
	cause all of the generated interfaces to extend the named interface,
	
      <tt>org.acme.RocketBooster</tt>.
    



	
    <a name="javaType"></a>
	
    <h3>Enhanced &lt;jaxb:javaType&gt;</h3>
	
    <p>
		The &lt;xjc:javaType&gt; customization can be used just like the standard &lt;jaxb:javaType&gt; customization, except that it allows you to specify an 
      <code>XmlAdapter</code>-derived class, instead of parse&amp;print method pair.
	
	
    
    <p>
		This customization can be used in all the places &lt;jaxb:javaType&gt; is used, but nowhere else:

      <pre class="code">
&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
           <font color="red">xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
           jaxb:extensionBindingPrefixes="xjc"</font>
           jaxb:version="2.0"&gt;
  .
  .
  .
  &lt;xsd:simpleType name="LayerRate_T"&gt;
    &lt;xsd:annotation&gt;&lt;xsd:appinfo&gt;
      <font color="red">&lt;xjc:javaType name="org.acme.foo.LayerRate"
        adapter="org.acme.foo.LayerRateAdapter" /&gt;</font>
    &lt;/xsd:appinfo&gt;&lt;/xsd:annotation&gt;
    ... gory simple type definition here ...
  &lt;/xsd:simpleType&gt;
&lt;/xsd:schema&gt;
</pre>

	
    
    <p>
		In the above example, 
      <tt>LayerRate_T</tt> simple type is adapted by 
      <tt>org.acme.foo.LayerRateAdapter</tt>, which extends from 
      <tt>XmlAdapter</tt>.
	

      <pre class="code">
&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
           <font color="red">xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
           jaxb:extensionBindingPrefixes="xjc"</font>
           jaxb:version="2.0"&gt;
  &lt;xsd:annotation&gt;&lt;xsd:appinfo&gt;
    &lt;jaxb:globalBindings&gt;
      <font color="red">&lt;xjc:javaType name="org.acme.foo.MyDateType" xmlType="xsd:dateTime"
        adapter="org.acme.foo.MyAdapterImpl" /&gt;</font>
    &lt;/jaxb:globalBindings&gt;
  &lt;/xsd:appinfo&gt;&lt;/xsd:annotation&gt;
  
  .
  .
  .
&lt;/xsd:schema&gt;
</pre>


    
    <p>
		In the above example, all the use of 
      <tt>xsd:dateTime</tt> type is adapter by 
      <tt>org.acme.foo.MyAdapterImpl</tt> to 
      <tt>org.acme.foo.MyDateType</tt>
	
	
	
	
      <a name="simple"></a>
	
    
    <h3>Experimental simpler&amp;better binding mode</h3>
	
    <p>
		This experimental binding mode can be enabled as a part of the global binding. See below:
	

      <pre class="code">
&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
           <font color="red">xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
           jaxb:extensionBindingPrefixes="xjc"</font>
           jaxb:version="2.0"&gt;

    &lt;xs:annotation&gt;
       &lt;xs:appinfo&gt;
          &lt;jaxb:globalBindings generateValueClass="false"&gt;
           <font color="red">&lt;xjc:simple /&gt;</font>
          &lt;/jaxb:globalBindings&gt;
       &lt;/xs:appinfo&gt;
    &lt;/xs:annotation&gt;
.
.
.
&lt;/xs:schema&gt;
</pre>
	
	
    
    <p>
		When enabled, XJC produces Java source code that are more concise and easier to use. Improvements include:
	
	
      <ol>
		
        <li>
			Some content model definitoins, such as 
          <tt>A,B,A</tt>, which used to cause an XJC compilation error and required manual intervention, now compile out of the box without any customization.
		
		
        </li>
        <li>
			Some content model definitions that used to bind to a non-intuitive Java class now binds to a much better Java class:

          <pre class="code">
// schema
&lt;xs:complexType name="foo"&gt;
	&lt;xs:choice&gt;
		&lt;xs:sequence&gt;
			&lt;xs:element name="a" type="xs:int" /&gt;
			&lt;xs:element name="b" type="xs:int" /&gt;
		&lt;/xs:sequence&gt;
		&lt;xs:sequence&gt;
			&lt;xs:element name="b" type="xs:int" /&gt;
			&lt;xs:element name="c" type="xs:int" /&gt;
		&lt;/xs:sequence&gt;
	&lt;/xs:choice&gt;
&lt;/xs:complexType&gt;

// before
class Foo {
    List&lt;JAXBElement&lt;Integer&gt;&gt; content;
}

// in &lt;xjc:simple&gt; binding
class Foo {
    Integer a;
    int b; // notice that b is effectively mandatory, hence primitive
    Integer c;
}
</pre>
		
		
        </li>
        <li>
			When repetable elements are bound, the method name will become plural.

          <pre class="code">
// schema
&lt;xs:complexType name="person"&gt;
	&lt;xs:sequence&gt;
		&lt;xs:element name="child"  type="xs:string" maxOccurs="unbounded" /&gt;
		&lt;xs:element name="parent" type="xs:string" maxOccurs="unbounded" /&gt;
	&lt;/xs:sequence&gt;
&lt;/xs:complexType&gt;

// before
public class Person {
    protected List&lt;String&gt; child;
    protected List&lt;String&gt; parent;
}

// in &lt;xjc:simple&gt; binding
public class Person {
    protected List&lt;String&gt; children;
    protected List&lt;String&gt; parents;
}
</pre>
	
        </li>
      </ol>

	
    
    <p>
		Once again, readers are warned that this is an 
      <b>experimental binding mode</b>, and therefore the binding is subject to change in future versions of the JAXB RI without notice. Please send feedbacks on this binding to 
      <tt>users@jaxb.dev.java.net</tt>



	
      <a name="treatRestrictionLikeNewType"></a>
	
    
    <h3>Alternative Derivation-by-restriction Binding Mode</h3>
	
    <p>
		Normally, the JAXB specification requires that a derivation-by-restriction be mapped to an inheritance betwee n two Java classes. This is necessary to preserve the type hierarchy, but one of the downsides is that the derived class does not really provide easy-to-use properties that reflect the restricted content model.
	
    <p>
		This experimental &lt;xjc:treatRestrictionLikeNewType&gt; changes this behavior by not preserving the type inheritance to Java. Instead, it generates two unrelated Java classes, both with proper properties. For example, given the following schema:

      <pre class="code">&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc" jaxb:extensionBindingPrefixes="xjc"
  xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" jaxb:version="2.0"
  elementFormDefault="qualified"&gt;
  
  &lt;xs:annotation&gt;&lt;xs:appinfo&gt;
    &lt;jaxb:globalBindings&gt;
      &lt;xjc:treatRestrictionLikeNewType /&gt;
    &lt;/jaxb:globalBindings&gt;
  &lt;/xs:appinfo&gt;&lt;/xs:annotation&gt;
  
  &lt;xs:complexType name="DerivedType"&gt;
    &lt;xs:complexContent&gt;
      &lt;xs:restriction base="ResponseOptionType"&gt;
        &lt;xs:sequence&gt;
          &lt;xs:element name="foo" type="xs:string"/&gt;
        &lt;/xs:sequence&gt;
      &lt;/xs:restriction&gt;
    &lt;/xs:complexContent&gt;
  &lt;/xs:complexType&gt;
  
  &lt;xs:complexType name="ResponseOptionType"&gt;
    &lt;xs:sequence&gt;
      &lt;xs:element name="foo" type="xs:string" maxOccurs="unbounded"/&gt;
    &lt;/xs:sequence&gt;
  &lt;/xs:complexType&gt;

&lt;/xs:schema&gt;</pre>
	
    
    <p>
		The generated 
      <tt>Derived</tt> class will look like this (comment and annotations removed for brevity):

      <pre class="code">public class DerivedType {
    protected String foo;

    public String getFoo() { return foo; }
    public void setFoo(String value) { this.foo = value; }
}</pre>
	
    
    <p>
		In contrast, without this customization the 
      <tt>Derived</tt> class would look like the following:

      <pre class="code">public class DerivedType extends ResponseOptionType {
  // it simply inherits List&lt;String&gt; ResponseOptionType.getFoo()
}</pre>



	
      <a name="substitutable"></a>
	
    
    <h3>Allow separate compilations to perform element substitutions</h3>
	
    <p>
		In an attempt to make the generated code easier to use, the JAXB specification sometimes choose bindings based on how certain feature is used. One of them is element substitution feature. If no actual element substitution happens in the schema, JAXB assumes that the element is not used for substitution, and generates code that assumes it.
	
    <p>
		Most of the time this is fine, but when you expect other "extension" schemas to be compiled later on top of your base schema, and if those extension schemas do element substitutions, this binding causes a problem (
      <a href="https://jaxb.dev.java.net/issues/show_bug.cgi?id=289">see example</a>.)
	
    
    <p>
		&lt;xjc:substitutable&gt; customization is a work around for this issue. It explicitly tells XJC that a certain element is used for element substitution head, even though no actual substitution might be present in the current compilation. This customization should be attached in the element declaration itself, like this:

      <pre class="code">&lt;xs:element name="Model" type="Model"&gt;
  &lt;xs:annotation&gt;&lt;xs:appinfo&gt;
    &lt;xjc:substitutable /&gt;
  &lt;/xs:appinfo&gt;&lt;/xs:annotation&gt;
&lt;/xs:element&gt;</pre>


    
    
    <hr>
    
    <div class="footer">
      $Revision: 1.1 $
      <br>
      $Date: 2007/12/05 00:49:15 $
    
    </div>
  
 

  </BODY>
</html>